Contents page

Rules for Tools/Functions Structure

Your Tool or Accessory can access about 100 Bars&Pipes routines that handle everything
from allocating events to displaying scrolling pop-up menus.  In addition, you are
given access to most of Bars&Pipes internal data registers.  All of this is kept in one
structure, called `functions'.  A pointer to this structure is placed in the pointer
variable `functions' when your Tool is first loaded.  Call these routines by jumping
indirectly through the pointer.  For example, to allocate an Event with the
`allocevent()' routine (see allocevent()), write this statement:

     event = (struct Event *) (*functions->allocevent)();

   All of the routines that you'll need are documented individually in this manual. The
Inovatools routines, which primarily assist with the user interface, are not included.
These routines are explained in the seventy eight pages of documentation that come with
the Inovatools 1 product.

   You can access most of the Bars&Pipes global variables from the functions data
structure.  Some that you may use:

     long functions->timenow;

   This holds the current system time.  It starts at 0 and counts up as the sequence
plays.  When the Transport is not running, this is a negative number, counting up, so
the PipeLinev can still properly process events.

     long functions->starttime;

   This holds the time of the song position pointer.  If the sequence is started from
the Play button, it will pick up from here, rather than at the beginning of the song.
Whenever the sequence stops, Bars&Pipes updates starttime to the time of the sequence
when it stops.

     long functions->padcutin; long functions->padcutout;

   If a ToolPad Tool is processing events, it can read these two flags to see the
position of the edit flags.  Even though the Toolize operation may occur in a Track
edit window or in the main window, the flag positions from the edit window or main
window are copied into these two global variables.  For example, when the Reverse Tool
reverses all notes between the edit flags, it checks the times in `padcutin' and
`padcutout' to know what those edit flags are. Remember, though, these are only valid
for PadTools, not PipeLine Tools.  Check the `EVENT_PADTOOL' bit in the Event to
determine whether you are operating in real time on a PipeLine or Toolizing from a
PadTool (more on Events in the next section. See Events. )

     char functions->songname[100];

   The user enters the song title in this array.  You are welcome to read it as well as
change it.

     struct Track *functions->tracklist;

   This points to the linked list of Tracks.  From this list, your program can access
each Track as well as the Tools, Clips, and Events therein.

     struct Clip functions->masterclip;

   This Clip structure is embedded in the functions structure and stores the global
Song Parameters.

     char functions->version;

   This is the Bars&Pipes version number.  When Bars&Pipes adds new features that
provide increased opportunities for Tools and Accessories, the version number will
increment.  Currently, the version number is 2 (Bars&Pipes 1.0d and 1.0e.)

     struct Screen *functions->screen;

   This Intuition Screen pointer addresses Bars&Pipes' Screen.  To create a window
within Bars&Pipes, set the `CUSTOMSCREEN' flag and point the WScreen variable at
`functions->screen' (see struct Functions).

     struct Window *functions->window;

   This is the Bars&Pipes main window.

     struct ToolMaster *functions->toolmasterlist;

   Bars&Pipes keeps track of all loaded Tools with this linked list of ToolMaster
structures.  To find a particular ToolMaster, scan this list, searching by the toolid
field of each ToolMaster.

     struct Accessory *functions->accesslist;

   Bars&Pipes keeps track of all loaded Accessories with this linked list of Accessory
structures.

   All of the system variables and functions are described in the header file `bars.h'.